package com.minimalist.common.config.bucket;

import java.time.Duration;
import java.util.Optional;

/**
 * 限流配置提供者接口
 * <p>
 * 该接口定义了获取和管理限流配置的标准方法，支持动态配置更新、
 * 配置验证、多种配置策略等功能。实现类可以提供静态配置、动态配置、
 * 基于系统指标的自适应配置等不同的限流策略。
 * </p>
 *
 * @author 11987
 * @since 1.0.0
 */
public interface RateLimitConfigProvider {

    /**
     * 获取当前的限流配置
     * <p>
     * 返回当前生效的限流配置，包括容量限制和补充间隔等参数。
     * 如果配置不可用或未初始化，应返回null。
     * </p>
     *
     * @return 当前的限流配置，如果不可用则返回null
     */
    default RateLimitConfig getRateLimitConfig() {
        return null;
    }

    /**
     * 获取指定标识符的限流配置
     * <p>
     * 支持为不同的客户端、API端点或业务场景提供不同的限流配置。
     * 默认实现返回通用配置。
     * </p>
     *
     * @param identifier 配置标识符（如客户端ID、API路径等）
     * @return 对应的限流配置
     */
    default RateLimitConfig getRateLimitConfig(String identifier) {
        return getRateLimitConfig();
    }

    /**
     * 获取安全的限流配置
     * <p>
     * 返回一个Optional包装的配置，避免空指针异常。
     * 如果配置不可用，返回空的Optional。
     * </p>
     *
     * @return 包装的限流配置
     */
    default Optional<RateLimitConfig> getSafeRateLimitConfig() {
        return Optional.ofNullable(getRateLimitConfig());
    }

    /**
     * 获取安全的指定标识符限流配置
     *
     * @param identifier 配置标识符
     * @return 包装的限流配置
     */
    default Optional<RateLimitConfig> getSafeRateLimitConfig(String identifier) {
        return Optional.ofNullable(getRateLimitConfig(identifier));
    }

    /**
     * 验证限流配置是否有效
     * <p>
     * 检查配置的各项参数是否在合理范围内，包括：
     * - 容量是否大于0
     * - 补充间隔是否为正数
     * - 其他业务规则验证
     * </p>
     *
     * @return true如果配置有效，否则false
     */
    default boolean isConfigValid() {
        RateLimitConfig config = getRateLimitConfig();
        if (config == null) {
            return false;
        }
        return config.getCapacity() > 0 && 
               config.getRefillInterval() != null && 
               !config.getRefillInterval().isNegative() && 
               !config.getRefillInterval().isZero();
    }

    /**
     * 验证指定标识符的限流配置是否有效
     *
     * @param identifier 配置标识符
     * @return true如果配置有效，否则false
     */
    default boolean isConfigValid(String identifier) {
        RateLimitConfig config = getRateLimitConfig(identifier);
        if (config == null) {
            return false;
        }
        return config.getCapacity() > 0 && 
               config.getRefillInterval() != null && 
               !config.getRefillInterval().isNegative() && 
               !config.getRefillInterval().isZero();
    }

    /**
     * 获取配置的描述信息
     * <p>
     * 返回当前配置提供者的描述信息，用于日志记录、监控和调试。
     * </p>
     *
     * @return 配置提供者的描述信息
     */
    default String getConfigDescription() {
        RateLimitConfig config = getRateLimitConfig();
        if (config == null) {
            return "No rate limit configuration available";
        }
        return String.format("RateLimit[capacity=%d, refillInterval=%s]", 
                           config.getCapacity(), config.getRefillInterval());
    }

    /**
     * 检查配置是否支持动态更新
     * <p>
     * 指示当前配置提供者是否支持运行时动态更新配置。
     * 静态配置提供者返回false，动态配置提供者返回true。
     * </p>
     *
     * @return true如果支持动态更新，否则false
     */
    default boolean supportsDynamicUpdate() {
        return false;
    }

    /**
     * 获取配置的优先级
     * <p>
     * 当存在多个配置提供者时，用于确定配置的优先级。
     * 数值越大优先级越高。默认优先级为0。
     * </p>
     *
     * @return 配置优先级
     */
    default int getConfigPriority() {
        return 0;
    }

    /**
     * 获取默认的限流配置
     * <p>
     * 提供一个合理的默认配置，用于配置不可用时的降级处理。
     * 默认配置：容量100，补充间隔1分钟。
     * </p>
     *
     * @return 默认的限流配置
     */
    default RateLimitConfig getDefaultConfig() {
        return new RateLimitConfig(100, Duration.ofMinutes(1));
    }

    /**
     * 获取配置或默认配置
     * <p>
     * 如果当前配置不可用或无效，则返回默认配置，确保系统始终有可用的限流配置。
     * </p>
     *
     * @return 当前配置或默认配置
     */
    default RateLimitConfig getConfigOrDefault() {
        RateLimitConfig config = getRateLimitConfig();
        return (config != null && isConfigValid()) ? config : getDefaultConfig();
    }

    /**
     * 获取指定标识符的配置或默认配置
     *
     * @param identifier 配置标识符
     * @return 对应配置或默认配置
     */
    default RateLimitConfig getConfigOrDefault(String identifier) {
        RateLimitConfig config = getRateLimitConfig(identifier);
        return (config != null && isConfigValid(identifier)) ? config : getDefaultConfig();
    }

    /**
     * 刷新配置
     * <p>
     * 触发配置的重新加载或刷新操作。对于静态配置提供者，
     * 此方法可能不执行任何操作。对于动态配置提供者，
     * 应重新从配置源加载最新的配置。
     * </p>
     */
    default void refreshConfig() {
        // 默认实现不执行任何操作
    }

    /**
     * 获取配置的最后更新时间戳
     * <p>
     * 返回配置最后一次更新的时间戳（毫秒）。
     * 对于静态配置，可以返回创建时间。
     * </p>
     *
     * @return 最后更新时间戳，如果不支持则返回0
     */
    default long getLastUpdateTimestamp() {
        return 0L;
    }

    /**
     * 检查配置是否已过期
     * <p>
     * 根据配置的有效期检查是否需要刷新。
     * 默认实现总是返回false（配置不过期）。
     * </p>
     *
     * @return true如果配置已过期，否则false
     */
    default boolean isConfigExpired() {
        return false;
    }
}
